Installing and Using the First Virtual API Utilities 
*****************************************************

What to Read Here
=================

There are three major portions to this document. 

 o Obtaining and installing the API Utilities 
 o Using the Shell API 
 o Using the C API 

(If you wonder why these are documented together, the Shell API is merely a 
main() for the C API.)

Obtaining the software 
=======================

If you are reading this document with a World Wide Web browser such as
Lynx or Mosaic, you can probably download the software automatically. The
fv-api files supply a general purpose Application Program Interface for C and
for anything that normally executes commands, such as a UNIX shell or Tcl or
Rexx.

To obtain the First Virtual Shell and C API programs, simply click here for a
UNIX "tar" file from the file "pub/code/fv-api/fv-api.tar" on the machine
"ftp.fv.com". If for some reason you cannot use your WWW browser to
download these files directly, feel free to FTP to ftp.fv.com as anonymous.
Then cd /pub/code/fv-api and then get the appropriate file for your
machine. (We plan support for non-Unix machines in the near future.) 

Then, read about how to install the software.

Installing the software 
========================

You need to install the First Virtual API Utilities to do most kinds
of automatic information sales (i.e., information sales without human
intervention on each sale). These utilities are written in C and
should compile easily on any machine with an ANSI compiler. If you
compiler does not accept function prototypes and other ANSI extensions
to the original K&R C, you can retrieve unproto5.tar from the same
place you got the API Utilities package (or any of many other archive
sites) and follow its instructions to turn your compiler into one that
handles ANSI constructs.

Unpack the files into a directory and chdir to that directory. Examine
the Makefile and set any options appropriate to your system. The
commented out default rule for ".c.o" is an example of how to use the
"unproto" program. The Makefile will create one of three final
results: the "fv" program, the "libfv.a" library, and the "fv_ls"
program. Ignore the last for now unless you plan to sell information
with an FTP server. First, type "make fv" to create the "fv" and
"libfv.a" files. Fix any errors that may occur due to programs (like
ranlib) that may be named differently on your system. Then type "fv"
to assure you get a (long) usage summary.

Install SGCP as a tcp service at port 440 in your /etc/services file
(if appropriate for your system). Try pinging "card.com" to assure you
have connectivity, then try "fv checkat card.com acct" where "acct" is
your First Virtual Account ID. If all is well, you should see "new" or
"active" as the result. (If you don't have an Account ID already, just
pick something and you'll see "invalid".) A response of "unavailable"
indicates that First Virtual's server could not be contacted or
encountered an error processing the request and probably means the API
Utilities are working but are somehow misconfigured.

Read the documentation that comes with the First Virtual API Utilities
now to see how to use the C library and the command-line interface for
various purposes. This document also describes how to create .$
files. These .$ files contain specification lines that configure how
much files associated with them should cost and who should be paid for
them. This is important if you plan to use the API Utilities for an
FTP server or in the context of a WorldWideWeb server with "autosell
or manusell" scripts.

Using the Shell API 
====================

There are a multitude of subcommands built into the "fv" command. Most
require some sort of .$ file to be present. Two that don't are "fv checkat"
(which we have already seen) and "fv trstdin". 

fv checkat 
+++++++++++

fv checkat takes two additional parameters on the command line: the
address of the Internet Information Commerce server to query (card.com)
and an Account ID to check on. The Account ID must be one parameter from
the shell, which means that if you include spaces or special characters, you
should quote or otherwise escape them. fv will print out one of the following: 

"unavailable" 
   meaning the server could not be reached or that an internal error
   occured. 
"active" 
   meaning that the account is in good standing. 
"suspended" 
   meaning that the account is in good standing but the owner has not
   answered his email lately. 
"invalid" 
   meaning that either the account does not exist or has been revoked,
   either for nonpayment or for declaring fraud. 

These are standard codes returned by the SGCS server, except (obviously) for
"unavailable." 

fv trstdin 
+++++++++++

This command takes exactly four more command line arguments. A typical
call is fv trstdin card.com transfer@card.com "/usr/lib/sendmail -t" 0
< trfile > respfile Here, card.com specifies the IP address to which a
SGCP connection will be established (on the port specified in
/etc/services), transfer@card.com specifies the email address to which
messages shall be sent if the SGCP protocol is not used, sendmail is
the program into which such an email message should be piped, and 0
indicates the order of preference, with 0 meaning first try SGCP, then
use email if that fails.

A full APPLICATION/Green-Commerce transfer-request is read from the
standard input (with either LF or CRLF line terminators) and ends with
either a period alone on a line or the end of file indication.

The return from the server is written to standard output (LF
separated, no CRs) terminated by a line with a single period and then
the standard output is closed. The result will always begin with "+OK"
or "-ERR", with a "-ERR" being generated automatically if the server
cannot be contacted and a "+OK" being generated if email was sent.

Advanced Shell Interfaces
+++++++++++++++++++++++++

Complete documentation on advanced shell interfaces, appropriate for
automatically selling files, is available in documentation that comes
with the programs.